home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / Vk / VkRunOnce2.z / VkRunOnce2
Text File  |  1998-10-20  |  13KB  |  331 lines
  1.  
  2.  
  3.  
  4. VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))                                                  VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      VkRunOnce2 - Allow an application to have only a single instance
  10.  
  11. IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
  12.      VkComponent : VkCallbackObject
  13.  
  14. HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
  15.      #include <Vk/VkRunOnce2.h>
  16.  
  17.  
  18. PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY
  19.    CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr////DDDDeeeessssttttrrrruuuuccccttttoooorrrr
  20.            VkRunOnce2(VkNameList *args, Boolean per_host);
  21.            ~VkRunOnce2();
  22.  
  23.  
  24.    RRRReeeettttrrrriiiieeeevvvviiiinnnngggg AAAArrrrgggguuuummmmeeeennnnttttssss
  25.            int numArgs();
  26.            char *arg(int index);
  27.  
  28.  
  29.    CCCCaaaallllllllbbbbaaaacccckkkkssss
  30.            const char *const invokedCallback;
  31.  
  32.  
  33. CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  34.      VkRunOnce2 is a subtle variation on VkRunOnce. Both classes allow
  35.      applications to specify that only a single instance of the application
  36.      can be run on any system at any one time. This is useful when
  37.      implementing applications that are meant to provide a system-wide service
  38.      for multiple applications. For example, an audio control program that
  39.      controls the volume an other parameters on a system should not normally
  40.      need to have multiple instantiations. However, various programs or
  41.      scripts might wish to launch the application, and have no way to know if
  42.      the program is already running.
  43.  
  44.      Using VkRunOnce2, such programs can simply be run as many times as
  45.      desired.  Only the first run will actually display the program.
  46.      Subsequent runs will notify the running instance, possibly passing some
  47.      arguments. The running instance will raise itself, and respond to any
  48.      arguments provided. The second instance of the application will simply
  49.      exit.
  50.  
  51.      The primary difference between VkRunOnce2 and VkRunOnce is that
  52.      VkRunOnce2 is more flexible, and can be invoked before instantiating
  53.      VkApp. This can be more efficient, in that an application can attempt to
  54.      notify the currently running process before it starts the possibly time-
  55.      consuming initialization process represented by VkApp and application-
  56.      defined subclasses. If this application is the first to be launched,
  57.      however, this approach is less efficient, since it opens the X display
  58.      twice.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))                                                  VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))
  71.  
  72.  
  73.  
  74. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
  75.    VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222
  76.             VkRunOnce2(Boolean autoRaise)
  77.             VkRunOnce2(VkNameList *args,
  78.                        Boolean per_host);
  79.             VkRunOnce2(char **args, int numArgs,
  80.                        Boolean per_host, Boolean autoRaise);
  81.  
  82.  
  83.           Initialize a VkRunOnce2 object. If this is the only current instance
  84.           of this program running on the system, this constructor establishes
  85.           this application as the sole runnable instance. Normally, "running
  86.           on this system" is defined to mean an application whose X DISPLAY is
  87.           set to the current display device. If per_host is TRUE, multiple
  88.           instances are allowed on any given display, so long as each instance
  89.           is running on a different host. Arguments may be passed as either a
  90.           character array, or a VkNameList object. If autoRaise is True, the
  91.           running application is raised when another instance is started.
  92.  
  93.           If this is the second time an application is run, and _a_r_g_s is
  94.           provided on either form, the VkRunOnce2 constructor makes contact
  95.           with the running instance, passing it any arguments supplied in the
  96.           args parameter. The constructor then causes the application to exit
  97.           by calling VkApp::terminate().
  98.  
  99.      If the first form of the VkRunOnce2 constructor is used, this process
  100.      does not occur. The process of contacting running processes and
  101.      establishing this process as the running process must be initiated
  102.      manually by calling notifyOthers() and takeCharge().
  103.  
  104.    ~~~~VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222
  105.               ~VkRunOnce2();
  106.  
  107.  
  108.           If the VkRunOnce2 object is deleted, and this application is the
  109.           current single instance of this application, multiple instances of
  110.           this program are then allowed to run.
  111.  
  112.    ccccllllaaaassssssssNNNNaaaammmmeeee
  113.               virtual const char* className();
  114.  
  115.  
  116.           The class name of this class is "VkRunOnce2".
  117.  
  118.    nnnnoooottttiiiiffffyyyyOOOOtttthhhheeeerrrrssss
  119.                void notifyOthers(VkNameList *,
  120.                               Boolean per_host = FALSE,
  121.                            const char *name = NULL);
  122.                void notifyOthers(char **args,  int numArgs
  123.                               Boolean per_host = FALSE,
  124.                            const char *name = NULL);
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))                                                  VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))
  137.  
  138.  
  139.  
  140.           This function is invoked to notify other running instances of this
  141.           application that a new one has started. Arguments provided to this
  142.           function are passed to the currently running instance. This function
  143.           never returns, the calling application exits after notifying the
  144.           running instance.
  145.  
  146.    ttttaaaakkkkeeeeCCCChhhhaaaarrrrggggeeee
  147.                void takeCharge();
  148.  
  149.  
  150.           This function establishes the calling application as the running
  151.           instance. It would typically be called after calling notifyOthers().
  152.  
  153. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  154.      The following program displays a string in a window. After the first
  155.      instance, subsequent instances of the program pass the first command line
  156.      argument to the running instance, to be displayed as a string in the
  157.      application's window.
  158.  
  159.  
  160.            #include <Vk/VkApp.h>
  161.            #include <Vk/VkRunOnce2.h>
  162.            #include <Vk/VkNameList.h>
  163.            #include <Vk/VkSimpleWindow.h>
  164.            #include <Xm/Label.h>
  165.  
  166.            // Define a top-level window class
  167.  
  168.            class RunOnceWindow: public VkSimpleWindow {
  169.  
  170.             protected:
  171.  
  172.                Widget _label;
  173.  
  174.  
  175.             public:
  176.  
  177.               RunOnceWindow ( const char *name ) :
  178.                            VkSimpleWindow ( name )
  179.               {
  180.                    _label =  XmCreateLabel ( mainWindowWidget(),
  181.                                              "first instance",
  182.                                               NULL, 0 );
  183.  
  184.                    addView(_label);
  185.               }
  186.  
  187.               ~RunOnceWindow();
  188.  
  189.               void update(VkComponent *comp, XtPointer, XtPointer);
  190.  
  191.               virtual const char* className() {
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))                                                  VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))
  203.  
  204.  
  205.  
  206.                                  return "RunOnceWindow";
  207.                               }
  208.            };
  209.  
  210.            RunOnceWindow::~RunOnceWindow()
  211.            {
  212.               // Empty
  213.            }
  214.  
  215.            void RunOnceWindow::update(VkComponent *comp,
  216.                                       void*,
  217.                                       void*)
  218.            {
  219.               // Just retrieve the arguments, Use the first string
  220.               // as a new label for the widget and the second
  221.               // as a color.
  222.  
  223.               VkRunOnce2 *obj = (VkRunOnce2*) comp;
  224.  
  225.               if(obj->numArgs() > 0)
  226.               {
  227.                   XtVaSetValues(_label,
  228.                                 XtVaTypedArg,
  229.                                 XmNlabelString, XmRString,
  230.                                 obj->arg(0),
  231.                                 strlen(obj->arg(0) ) + 1,
  232.                                 NULL);
  233.               }
  234.            }
  235.  
  236.  
  237.            // Main driver. Instantiate a VkApp and a top-level
  238.            // window, "show" the window and then "run" the
  239.            // application. The VkRunOnce2 object prevents
  240.            // multiple instances of the application.
  241.  
  242.            void main ( int argc, char **argv )
  243.            {
  244.  
  245.               // Instantiate VkRunOnce and notify other
  246.               // running instances, if any
  247.  
  248.               VkRunOnce2 *runOnce = new VkRunOnce2();
  249.               ro->notifyOthers(argv, argc);
  250.  
  251.               // If we get here, this is the first running instance
  252.               // so proceed with creating a VkApp object
  253.  
  254.               VkApp        *app = new VkApp("RunOnce", &argc, argv);
  255.  
  256.               // Now, establish this process as the first running
  257.               // instance of this  application
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))                                                  VVVVkkkkRRRRuuuunnnnOOOOnnnncccceeee2222((((3333xxxx))))
  269.  
  270.  
  271.  
  272.               ro->takeCharge();
  273.  
  274.               // Create a window
  275.  
  276.               RunOnceWindow  *win = new RunOnceWindow("hello");
  277.  
  278.               // Register a callback for running applications
  279.               // to receive if anyone attempts to run this
  280.               // application again.
  281.  
  282.               VkAddCallbackMethod(VkRunOnce2::invokedCallback, runOnce,
  283.                                   win, RunOnceWindow::update, NULL);
  284.  
  285.               win->show();
  286.               app->run();
  287.            }
  288.  
  289.  
  290.  
  291. IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
  292.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCoooommmmppppoooonnnneeeennnntttt
  293.           installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
  294.           setDefaultResources(), getResources(), manage(), unmanage(),
  295.           baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback
  296.  
  297.  
  298.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCaaaallllllllbbbbaaaacccckkkkOOOObbbbjjjjeeeecccctttt
  299.           callCallbacks(), addCallback(), removeCallback(),
  300.           removeAllCallbacks()
  301.  
  302.  
  303. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  304.      VkApp(3x), VkRunOnce
  305.      _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e
  306.      _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Sheifler and Jim Gettys
  307.      _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick
  308.      _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.